/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			uvarary.h
  \date			Dec 2011
  \author		TNick

  \brief		Contains the definition for UVarAry class


*//*


 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Please read COPYING and README files in root folder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __UVARARY_INC__
#define __UVARARY_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

#include	<uservar.h>
#include	<defvar.h>


/*  INCLUDES    ============================================================ */
//
//
//
//
/*  CLASS    --------------------------------------------------------------- */
namespace	PgScr	{

class	UVarAry		: public DefVar {

	//
	//
	//
	//
	/*  DEFINITIONS    ----------------------------------------------------- */

public:

	/*  DEFINITIONS    ===================================================== */
	//
	//
	//
	//
	/*  DATA    ------------------------------------------------------------ */

public:

	/*  DATA    ============================================================ */
	//
	//
	//
	//
	/*  FUNCTIONS    ------------------------------------------------------- */



public:

	/// constructor
	UVarAry				( void );


	/// destructor;
	virtual				~UVarAry			( void );


	/**
	*	@brief	get a string representation of the object / variable
	*/
	QString				presentation	(VarStore *uv = NULL );


	/**
	*	@brief	resetContent resets the variable and frees any resources
	*/
	void				resetContent	( VarStore * uv = NULL );


	/**
	*	@brief	set default value
	*/
	void				setDefault		( VarStore * uv = NULL );


	/**
	*	@brief	describes in a short string the type of undelying storage
	*
	*/
	QString				typeName		( VarStore * uv = NULL );


	/** @name Retrieving common values
	*
	*/
	//@{

	bool				convToBool		( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return false; }

	qint16				convToShort		( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return 0; }

	qint32				convToInt		( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return 0; }

	qint64				convToLong		( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return 0; }

	qint8				convToByte		( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return 0; }

	qreal				convToDouble	( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return 0.0; }

	QStringList			convToStrLst	( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return QStringList(); }

	QString				convToStr		( bool * b_ok, VarStore * uv = NULL )
	{ Q_UNUSED( uv ); *b_ok = false; return QString(); }

	//@}



	/**
	*	@brief	tell if this type of variable may be saved (is saveable)
	*
	*	@return	true if variable can be saved, false otherwise
	*/
	bool				canSave			( VarStore * uv = NULL );


	/**
	*	@brief	save the content of the variable
	*
	*	The variable is saved as a group at current path. The name of the
	*	group is given by the name of the variable and, inside, the type and
	*	actual value are saved using \b TAG_NAME_TYPE and \b TAG_NAME_VALUE.
	*
	*	@return	true if variable was saved, false otherwise

	*/
	bool				save			(
			PgSave::IPgSave &		stg,
			VarStore *				uv = NULL
			);


	/**
	*	@brief	load the content of the variable
	*
	*	The variable is saved as a group at current path. The name of the
	*	group is given by the name of the variable and, inside, the type and
	*	actual value are saved using \b TAG_NAME_TYPE and \b TAG_NAME_VALUE.
	*
	*	@return	true if variable was loaded, false otherwise
	*/
	bool				load			(
			PgSave::IPgSave &		stg,
			VarStore *				uv = NULL
			);


	/**
	*	@brief	create an array of given size and type
	*
	*	This will use UserVar::resetContent() before performing requested
	*	changes on target variable.
	*
	*	The function is only usble for one level arrays.
	*
	*	@param	trg_var	the variable to change
	*	@param	el_cnt	number of elements to create
	*	@param	ary_ty	type of each element
	*/
	static void		setValArray	(
			UserVar *	trg_var,
			int			el_cnt,
			StoreType	ary_ty
			);


	/**
	*	@brief	create an array of given structure and type
	*
	*	This will use UserVar::resetContent() before performing requested
	*	changes on target variable.
	*
	*	The function may be used with nested arrays of any level. \b el_cnt_l1
	*	is the number of elements on first level (at the top of the tree).
	*	Each integer that follows represents number of elements on nested level.
	*
	*	@param	trg_var	the variable to change
	*	@param	el_cnt_l1	number of elements to create
	*	@param	ary_ty	type of each element
	*/
	static void		setValArray	(
			UserVar *	trg_var,
			StoreType	ary_ty,
			int			el_cnt_l1,
			... );





public:


	/**
	*	@brief	creates an variable of this type based on settings
	*/
	static bool		blindCreate		(
			PgSave::IPgSave *	intf,
			QString				s_path,
			void *				kb_data
			);


private:


	/**
	*	@brief	used internally to recursivelly add levels
	*/
	static void		addLevel		(
			VarStore *	uv,
			int			el_cnt,
			StoreType	ary_ty
			);




	/*  FUNCTIONS    ======================================================= */
	//
	//
	//
	//

};

/*  CLASS    =============================================================== */
//
//
//
//

#ifdef	PGSCRIPT_TESTS
void				VarArray_Tests					(
		int & performed,
		int & succeded
		);
#endif

}	//	namespace	PlayGr

#endif // __UVARARY_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
